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Overview 

The  AE-9/AP-9  Radiation  Belt  model  is  distributed  with  a  GUI  client  application  and  a  command-line 
driven  utility  application  that  can  be  used  to  run  the  model  either  interactively  or  through  batch  driven 
processes.  For  situations  in  which  it  is  more  appropriate  to  integrate  the  AE-9/AP-9  model  calls  and  data 
directly  into  a  new  or  existing  application,  an  Application  Programming  Interface  (API)  is  also  distributed 
with  the  model. 

The  AE-9/AP-9  Radiation  Belt  model  supports  programmatic  access  through  a  suite  of  APIs  accessible 
from  a  number  of  programming  languages.  The  model  is  written  in  C++  and  direct  access  to  all  classes 
and  methods  of  the  model  is  available  using  the  source  distribution  of  the  model.  Additional  APIs  are 
provided  through  a  set  of  C  and  Fortran  wrapper  methods  at  the  highest  level  of  the  model,  using  a  set 
of  "fly-in"  routines  modeled  after  those  found  in  the  Irbemlib  API. 

Getting  Started 

Installation  and  Setup 

AE-9/AP-9  is  distributed  as  a  zip  file  that  comes  with  a  pre-built  Windows  32-bit  binary  distribution  of 
the  model  and  a  complete  set  of  source  for  building  API  libraries,  as  well  as  binary  distributions  for  other 
platforms.  To  generate  a  set  of  libraries,  shared  objects  and/or  dll  files,  please  refer  to  the  build 
instructions  provided  with  the  distribution  in  Ae9Ap9/documents/  Build_lnstructions_for_AE9AP9.pdf. 

Note  that  the  source  distribution  build  process  uses  CMake  to  generate  an  "out-of-source"  build.  That 
means  that  output  binary  and  library  files  are  located  in  a  separate  directory  structure  from  the  source 
files.  This  is  done  to  facilitate  builds  for  multiple  platforms,  as  well  as  debug  and  release  builds  for  any 
given  platform.  Flowever,  the  ramification  of  this  is  that  the  location  of  libraries  and  header  files  will 
depend  on  the  choices  made  during  the  build  process  and  may  vary.  This  is  reflected  in  the  library  paths 
shown  below  through  the  use  of  curly  brackets  '{}'. 

The  following  directories  within  the  AE-9AP-9  distribution  will  contain  header  files  that  may  be  required 
to  compile  an  application  that  utilizes  the  AE-9AP-9  libraries: 

...  Ae9Ap9/source/Ae9Ap9/trunk/models/include 
...  Ae9Ap9/source/SpWx_Ae9Ap9/Common/include 
...  Ae9Ap9/source/SpWx_Ae9Ap9/Models/include 


After  performing  a  source  build,  the  following  directories  within  the  AE-9AP-9  distribution  will  contain 
library,  shared  object  and/or  dll  files  that  may  be  required  to  link  and  run  an  application  with  AE-9AP-9 
libraries. 

...  Ae9Ap9/source/build_{linux |  win32}/Ae9Ap9/trunk/lib{/debug |  release} 

...  Ae9Ap9/source/build_{linux |  win32}/Ae9Ap9_SpWx/Models/lib{/windows/Debug.Net  |  Release. Net} 


Approved  for  public  release;  distribution  is  unlimited. 

1 


Shared  Objects,  DLLs  and  Static  Libraries 

Applications  can  link  to  the  AE-9  model  using  static  libraries  or  through  DLLs  under  Windows  or  shared 
object  files  under  Linux  operating  systems.  To  run  an  application  that  references  the  AE-9  through  either 
DLL  or  shared  object  implementations,  those  binaries  must  be  moved  to  a  directory  specified  in  the 
PATH  (Windows)  or  LD_LIBRARY_PATH  (Linux)  environment  variables.  Alternatively,  the  directories  in 
which  they  reside  can  be  added  to  those  path  specifications.  Those  directories  are  as  follows: 

...Ae9Ap9/source/build_win32/Ae9Ap9/trunk/bin{/Debug  I  Release}  -  ae9ap9.dll 
...Ae9Ap9/source/buildJinux/Ae9Ap9/trunk/lib  -  libae9ap9.so 
...Ae9Ap9/source/buildJinux/Ae9Ap9_SpWx/Models/lib  -  various  shared  objects 

C++ API 

The  AE-9/AP-9  application  is  written  in  C++  and  all  source  and  header  files  are  provided  with  the 
distribution.  This  gives  the  client  application  developer  a  great  deal  of  freedom  in  determining  at  what 
level  and  granularity  to  integrate  with  the  model.  However,  for  most  applications  it  is  recommended 
that  client  applications  access  the  model  through  the  top  level  "Application"  layer.  The  application  layer 
consists  of  the  Ae9Ap9Application  and  AEOrbitPropagator  classes,  along  with  a  small  suite  of  optional 
aggregation  classes  derived  from  the  AEAggregator  class.  These  classes  and  their  methods  are  described 
in  detail  in  the  C++  API  Reference  section  of  this  document. 

A  note  to  Windows  C++  developers:  The  AE-9/AP-9  classes  heavily  utilize  STL  containers  and  classes  as 
method  parameters.  This  makes  it  problematic  to  expose  these  methods  across  a  dll  boundary.  Only 
functions  of  the  C  API  are  exposed  from  the  ae9ap9.dlL  Therefore,  it  is  recommended  that  on  the 
Windows  platform,  C++  client  applications  either  link  statically  to  AE-9/AP-9  libraries  or  call  the  model 
through  the  C  interface  methods  to  use  the  dll.  On  Linux  platforms,  client  applications  can  use  the  C++ 
API  to  call  directly  into  the  shared  object  implementation  of  the  model. 

CAPI 

The  AE-9/AP-9  C  language  API  is  provided  for  access  to  the  model  from  C  and  other  compatible  language 
client  applications.  It  can  also  be  used  to  access  the  DLL  implementation  of  the  model  on  the  Windows 
platform  from  C++  applications.  The  C  API  utilizes  client  allocated  array  data  structures  in  place  of 
collection  classes  used  by  the  underlying  C++  interface  and  classes.  Note  that  the  C  API  assumes  that  all 
buffers  for  return  data  are  allocated  at  the  client  application  level  and  that  relevant  sizes  are  passed  into 
the  API  by  the  calling  routine.  This  is  intended  to  eliminate  any  ambiguity  as  to  responsibility  for 
memory  allocation  and  deallocation  and  to  reduce  or  eliminate  memory  leaks.  The  AE-9/AP-9  C 
language  API  is  defined  in  the  file  AECInterface.h.  The  methods  of  this  interface  are  described  in  detail  in 
the  C  API  Reference  section  of  this  document. 

Fortran  API 

The  AE-9/AP-9  Fortran  language  API  is  provided  for  access  to  the  model  from  Fortran  and  other 
compatible  language  client  applications.  The  Fortran  API  is  comparable  to  the  C  API,  however,  native 
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Fortran  applications  pass  data  by  reference  and  use  different  calling  conventions.  The  Fortran  API  also 
utilizes  client  allocated  array  data  structures  in  place  of  collection  classes  used  by  the  underlying  C++ 
interface  and  classes.  Note  that  the  Fortran  API  assumes  that  all  buffers  for  return  data  are  allocated  at 
the  client  application  level  and  that  relevant  sizes  are  passed  into  the  API  by  the  calling  routine.  This  is 
intended  to  eliminate  any  ambiguity  as  to  responsibility  for  memory  allocation  and  deallocation  and  to 
reduce  or  eliminate  memory  leaks.  The  AE-9/AP-9  Fortran  language  API  is  defined  in  the  file 
AEFInterface.h.  The  methods  of  this  interface  are  described  in  detail  in  the  Fortran  API  Reference 
section  of  this  document. 

3rd  Party  Dependencies 

The  AE-9/AP-9  model  has  dependencies  on  the  external  3'^'^  party  libraries  Boost®  (for  linear  algebra 
functions  and  data  structures)  and  on  FIDF5®  (for  internal  databases).  Please  refer  to  the 
Build_lnstructions_for_AE9AP9.pdf  document  in  the  Ae9Ap9/documents  directory  for  details  on 
installation  of  these  libraries.  It  is  likely  that  include  and  library  directories  from  these  installations  will 
need  to  be  added  to  build  settings  for  client  applications  and  that  shared  binaries  will  need  to  be  added 
to  the  appropriate  system  paths. 
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API  Reference 


C++ API 

Ae9Ap9Application  Class 

Header  file:  Ae9Ap9Application.h 

Description:  This  class  is  the  main  entry  point  into  the  application  layer  of  the  Ae9Ap9  project. 

The  Ae9Ap9Application  class  provides  a  suite  of  methods  that  provide  synchronous 
access  to  the  underlying  Ae9Ap9  model.  Client  applications  requiring  multi-processing 
capabilities  should  access  the  model  through  the  underlying  Ae9Ap9Model  class. 


Public  methods: 


Ae9Ap9Application 


Usage: 


Default  constructor 


Parameters:  none 

Return  values:  none 


''A  e9Ap9Applica  tion 


Usage:  Destructor 

Parameters:  none 

Return  values:  none 


void  setModelDataSource 

(const  Strings  strDataSource ) 


Usage:  Set  the  path  and  file  name  of  the  hdfS  format  database  containing 
the  data  of  the  selected  model,  (ie:  for  high  energy  electrons,  pass 
"{path}/  AE9V10_runtime_tables.mat")  Call  this  once  at  startup  to 
initialize  the  model. 
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Parameters: 

strDataSource  -  path  and  file  name  of  the  hdf5  database 
Return  values:  none 


void  setKPhiNeuralNetDataSource 

(  const  stringSi  strDataSource ) 

Usage:  Set  the  path  and  file  name  of  the  hdfS  format  database  containing 
the  K/Phi  space  neural  network  used  by  the  selected  model. 

(ie:  pass  "{path}/  fastPhi_net.mat")  Call  this  once  at  startup  to  initialize 
the  model. 

Parameters: 

StrDataSource  -  path  and  file  name  of  the  hdfS  neural  net  database 
Return  values:  none 


void  setKHMinNeuralNetDataSource 

(  const  Strings  strDataSource  ) 

Usage:  Set  the  path  and  file  name  of  the  hdfS  format  database  containing 
the  K/Hmin  space  neural  network  used  by  the  selected  model. 

(ie:  pass  "{path}/  fast_hmin_net.mat")  Call  this  once  at  startup  to 
initialize  the  model. 

Parameters: 

StrDataSource  -  path  and  file  name  of  the  hdfS  neural  net  database 
Return  values:  none 


void  setMagfieldModelDataSource 

(  const  Strings  strDataSource  ) 

Usage:  Set  the  path  and  file  name  of  the  hdfS  format  database  containing 
the  magnetic  field  model  data  used  by  the  selected  model. 

(ie:  pass  "{path}/  igrfDB.hS") .  Call  this  once  at  startup  to  initialize 
the  model. 

Parameters: 

StrDataSource  -  path  and  file  name  of  the  hdfS  database 
Return  values:  none 
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int  setFluxEnvironment 


( eModelType,  eFIuxType,  vvdEnergies, 
vdTimes,  eCoordSys,  vdCoordsAxisl, 
vdCoordsAxiZ,  vdCoordsAxis3  ) 

Usage:  This  method  computes  flux  weights  for  a  grouping  of  satellite 
positions  at  a  given  set  of  energies  and  times  when  computing 
omnidirectional  flux.  It  should  be  called  once  prior  to  calling 
any  combination  of  fly-in  flux  computation  methods  for  that 
time  period.  Note:  use  as  large  a  grouping  of  satellite 
positions  as  can  be  processed  on  available  hardware. 

Parameters: 

eModel  -  type  of  model  to  be  run:  eAEModelElectron,  eAEModelProton, 
eAEModelSpecies 

eFIuxType  -  enum  defining  type  of  flux  to  compute  (1  point  differential,  2  point 
differential,  integral)  see  AEEnums.h 

vvdEnergies  -  2  dimensional  vector  of  doubles  defining  energy  levels  (MeV) 
at  which  to  compute  flux.  Note:  column  2  used  only  for  2  pt 
differential  flux  type,  which  requires  computation  of  flux  between 
two  energy  levels 

vdTimes  -  vector  of  date/times  in  modified  Julian  date  format  at  which  to 
compute  flux.  Lengths  of  time  and  position  vectors  must  match, 
with  time  corresponding  to  a  position  at  that  index  in  the  vectors. 
eCoordSys  -  enum  defining  the  coordinate  system  of  positions  and  directions 
vdCoordsAxisl, 
vdCoordsAxis2, 

vdCoordsAxis3  -  Coordinates  along  axes  in  3d  space  in  the  eCoordSys  coordinate 
system  of  each  position  at  which  flux  is  to  be  computed.  These  vectors 
should  match  the  vdTimes  vector  in  length  and  correspond  to  those 
times  at  each  position. 


Return  values: 

int  -  0  success,  else  (see  AEErrors.h) 


int  setFluxEnvironment 

(eModelType,  eFIuxType,  vvdEnergies, 
vdTimes,  eCoordSys,  vdCoordsAxisl, 
vdCoordsAxi2,  vdCoordsAxis3, 
vvdFluxDirl,  vvdFluxDir2,  vvdFluxDir3  ) 

Usage:  This  method  computes  flux  weights  for  a  grouping  of  satellite 
positions  at  a  given  set  of  energies  and  times  when  computing 
directional  flux.  This  method  provides  an  alternative  to  computing  a  single 
omnidirectional  flux.  It  allows  the  user  to  specify  one  or  more  flux  directions  at 
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each  time  and  position.  The  flux  for  each  combinatin  of  passed  time,  position 
and  direction  will  be  computed. 

Flux  directions  should  be  passed  as  x,y,z  components  of  unit  vectors  using  the 
passed  coordinate  system.  This  method  should  be  called  once  prior  to  calling 
any  combination  of  fly-in  flux  computation  methods  for  that  time  period. 
Note:  use  as  large  a  grouping  of  satellite  positions  as  can  be  processed  on 
available  hardware. 

Parameters: 

eModel  -  type  of  model  to  be  run:  eAEModelElectron,  eAEModelProton, 
eAEModelSpecies 

eFIuxType  -  enum  defining  type  of  flux  to  compute  (1  point  differential,  2  point 
differential,  integral)  see  AEEnums.h 

vvdEnergies  -  2  dimensional  vector  of  doubles  defining  energy  levels  (MeV) 
at  which  to  compute  flux.  Note:  column  2  used  only  for  2  pt 
differential  flux  type,  which  requires  computation  of  flux  between 
two  energy  levels 

vdTimes  -  vector  of  date/times  in  modified  Julian  date  format  at  which  to 
compute  flux.  Lengths  of  time  and  position  vectors  must  match, 
with  time  corresponding  to  a  position  at  that  index  in  the  vectors. 
eCoordSys  -  enum  defining  the  coordinate  system  of  positions  and  directions 
vdCoordsAxisl, 
vdCoordsAxis2, 

vdCoordsAxis3  -  Coordinates  along  axes  in  3d  space  in  the  eCoordSys  coordinate 
system  of  each  position  at  which  flux  is  to  be  computed.  These  vectors 
should  match  the  vdTimes  vector  in  length  and  correspond  to  those 
times  at  each  position. 
vvdFluxDirl, 
vvdFluxDir2, 

vvdFluxDir3  -  Directions  at  which  to  compute  flux  at  each  timestep  in  vdTimes. 

Multiple  directions  can  be  computed  at  each  timestep.  Thus,  these 
vectors  are  2  dimensional  (nTimes,nDirections). 


Return  values: 

int  -  0  success,  else  (see  AEErrors.h) 


intflyInMean 

( vvdvector&  vvvdFluxData  ) 

Usage:  This  method  computes  mean  flux  at  each  position,  time,  energy  and 

optionally  direction  passed  in  the  most  recent  call  to  setFluxEnvironment. 
Bad  values  are  returned  as  AE_NaN  (defined  in  AEErrors.h).  The  function 
ae9ap9::isnan(value)  should  be  used  to  test  for  bad  values. 

Parameters: 

vvvdFluxData  -a  returned  3  dimensional  vector  (time,  energy,  direction) 
of  flux  values  (in  MeV) 
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Return  Values: 

int  -  0  success,  else  (see  AEErrors.h) 
int  flyInPerturbedMean 

( int  iScenario,  vvdvector&  vvvdFluxData ) 

Usage:  This  method  computes  perturbed  mean  flux  at  each  position,  time,  energy  and 
optionally  direction  passed  in  the  most  recent  call  to  setFluxEnvironment. 
Perturbed  means  are  a  statistical  distribution  of  mean  flux  based  on 
measurement  uncertainty  only.  Bad  values  are  returned  as  AE_NaN  (defined 
in  AEErrors.h).  The  function  ae9ap9::isnan(value)  should  be  used  to  test  for 
bad  values. 

Parameters: 

iScenario  -  perturbed  mean  scenario  number  (1..999)  for  repeatability 
vvvdFluxData  -  a  returned  3  dimensional  vector  (time,  energy,  direction) 
of  flux  values  (in  MeV) 

Return  Values: 

int  -  0  success,  else  (see  AEErrors.h) 


in  t  flyInPercen  tile 

( int  iPercentile,  vvdvector&  vvvdFluxData  ) 

Usage:  This  method  computes  percentile  flux  at  each  position,  time,  energy  and 
optionally  direction  passed  in  the  most  recent  call  to  setFluxEnvironment. 

Bad  values  are  returned  as  AE_NaN  (defined  in  AEErrors.h).  The  function 
ae9ap9::isnan(value)  should  be  used  to  test  for  bad  values. 

Parameters: 

iPercentile  -  percentile  (1..99)  flux  to  compute  at  each  time,  energy  and  position 
vvvdFluxData  -  a  returned  3  dimensional  vector  (time,  energy,  direction) 
of  percentile  flux  values  (in  MeV) 

Return  Values: 

int  -  0  success,  else  (see  AEErrors.h) 


int  fiyinScenario 

(dEpoch,  iScenario,  vvvdFluxData,  bPerturbFIuxMap  =  true  ) 

Usage:  This  method  computes  monte  carlo  flux  at  each  position,  time,  energy  and 
optionally  direction  passed  in  the  most  recent  call  to  setFluxEnvironment. 
Monte  carlo  fluxes  are  a  statistical  distribution  of  flux  based  on  both 
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measurement  and  temporal  uncertainty.  Bad  values  are  returned  as 
AE_NaN  (defined  in  AEErrors.h).  The  function  ae9ap9::isnan(value)  should 
be  used  to  test  for  bad  values. 

Parameters: 

dEpoch  -  start  date/time  (in  Modified  Julian  Date)  for  the  scenario 
iScenario  -  monte  carlo  scenario  number  (1..999)  for  repeatability 
vvdFluxData  -  a  returned  3  dimensional  vector  (time,  energy,  direction) 
of  percentile  flux  values  (in  MeV) 

bPerturbFIuxMap  -  if  false,  turns  off  measurement  uncertainty  mean 
perturbation.  Do  Not  Use.  For  testing  purposes  only. 

Return  Values: 

int  -  0  success,  else  (see  AEErrors.h) 


const  stringSi  getErrorText 

Usage:  Retrieves  the  text  associated  with  a  non-zero  returned  error  code 
Parameters:  none 
Return  Values: 

const  string&  -  text  associated  with  a  previously  returned  error  code 


AEOrbitPropagator  Class 

Fleaderfile:  AEOrbitPropagator.h 

Description:  This  class  encapsulates  three  choices  of  underlying  orbit  propagator 

implementations;  an  SGP4-based  propagator,  a  SatEph  implementation  and 
a  Kepler+J2  only  propagator.  Clients  of  this  class  can  choose  which  to  use. 

Public  methods: 

AEOrbitPropagator 

Usage:  Default  constructor 

Parameters:  none 

Return  values:  none 
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'AEOrbitPropagator 


Usage:  Destructor 

Parameters:  none 

Return  values:  none 

void  setPropagatorTypeSGP4 

Usage:  Forces  use  of  the  SGP4  orbit  propagator  (default) 

Parameters:  none 
Return  values:  none 

void  setPropagatorTypeSatEph 

Usage:  Forces  use  of  the  SatEph  orbit  propagator 
Parameters:  none 
Return  values:  none 

void  setPropagatorTypeKepler 

Usage:  Forces  use  of  the  Kepler-J2  orbit  propagator 
Parameters:  none 
Return  values:  none 

void  useSGP4lm  proved  Mode 

(  bool  bUse  ) 

Usage:  Enables  or  disables  use  of  the  "improved  mode"  when  using  the 
SGP4  propagator 
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Parameters: 

bUse  -  if  true,  enables  "improved  mode",  else  uses  standard  mode 
Return  values:  none 

void  setSGP4WGSConst720ld 

Usage:  Sets  use  of  the  WGS  1972  Old  mode  constant  datum  for  SGP4 
Parameters:  none 
Return  values:  none 

void  setSGP4WGSConst72 

Usage:  Sets  use  of  the  WGS  1972  newer  constant  s  when  using  SGP4 
Parameters:  none 
Return  values:  none 

void  setSGP4WGSConst84 

Usage:  Sets  the  use  of  WGS  1984  datum  constants  when  using  SGP4 
Parameters:  none 
Return  values:  none 


void  setTLEFile 

(  const  Strings  strTLEFile  ) 

Usage:  Sets  the  name  of  a  TIE  (two  line  element)  file  to  be  used  in  orbit  propagation 
Parameters: 

StrTLEFile  -  path  and  file  name  of  the  TLE  file  to  read 
Return  values:  none 
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void  clearTLEFields 


Usage:  Resets  all  internal  TLE-related  fields  to  default  values 
Parameters:  none 
Return  values:  none 


void  addTLE 

( const  string&  strTLELinel, 
long  ISatelliteNumber, 
char  cClass, 
int  iIntDesYear, 
int  iLaunchNumber, 
const  string&  strPiece, 
int  iEpochYear, 
double  dEpochDayOfYear, 
double  dMeanMotionlstDeriv, 
double  dMeanMotionZndDeriv, 
double  dBStar, 
int  lEphemType, 
int  lElementNumber, 
const  string&  strTLELinel, 
double  dinclination, 
double  dRightAscension, 
double  dEccentricity, 
double  dArgofPerigee, 
double  dMeanAnomaly, 
double  dMeanMotion, 
long  lEpochRevolution 
) 


Usage:  Adds  a  set  of  fields  defining  a  two  line  element  to  an  internal 
collection  of  TLEs  to  be  used  in  orbit  propagation 

Parameters: 

StrTLELinel  -  string  representing  line  1  of  the  two  line  element 

ISatelliteNumber  -  five  digit  satellite  number 

cClass  -  character  classification  'U'  for  unclassified 

iIntDesYear  -  last  two  digits  of  launch  year 

iLaunchNumber-  launch  number  of  the  year 

StrPiece  -  piece  of  the  launch 

iEpochYear  -  last  two  digits  of  the  year 
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dEpochDayOfYear  -  day  and  fractional  day 
dMeanMotionlstDeriv  -  first  derivative  of  mean  motion 
dMeanMotionZndDeriv  -  second  derivative  of  mean  motion 
dBStar  -  b  star  drag  term 
iEphemType  -  ephemeris  type 
iElementNumber  -  element  number 

strTLELineZ  -  string  representing  line  2  of  the  two  line  element 
dinclination  -  inclination  in  degrees 

dRightAscension  -  right  ascension  of  ascending  node  in  degrees 

dEccentricity  -  eccentricity 

dArgofPerigee  -  argument  of  perigee  in  degrees 

dMeanAnomaly  -  mean  anomaly  in  degrees 

dMeanMotion  -  mean  motion  in  revs  per  day 

lEpochRevolution  -  revolution  number  at  epoch 


Return  values:  none 


void  setTLEs 

( const  vector<string>&  vstrTLELinels, 
const  vector<long>&  vISatelliteNumbers, 
const  vector<char>&  vcClasses, 
const  vector<int>&  vilntDesYears, 
const  vector<int>&  viLaunchNumbers, 
const  vector<string>&  vstrPieces, 
const  vector<int>&  viEpochYears, 
const  vector<double>&  vdEpochDaysOfYear, 
const  vector<double>&  vdMeanMotionlstDerivs, 
const  vector<double>&  vdMeanMotionZndDerivs, 
const  vector<double>&  vdBStars, 
const  vector<int>&  viEphemTypes, 
const  vector<int>&  viElementNumbers, 
const  vector<string>&  vstrTLELinels, 
const  vector<double>&  vdinclinations, 
const  vector<double>&  vdRightAscensions, 
const  vector<double>&  vdEccentricities, 
const  vector<double>&  vdArgsofPerigee, 
const  vector<double>&  vdMeanAnomaUes, 
const  vector<double>&  vdMeanMotions, 
const  vector<long>&  vIEpochRevolutions 
) 


Usage:  Uses  a  set  of  field  vectors  defining  two  line  elements  to  populate 
an  internal  collection  of  TLEs  to  be  used  in  orbit  propagation 
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Parameters: 

vstrTLELinels  -  vector  of  strings  representing  line  1  of  the  two  line  elements 

vISatelliteNumbers  -  vector  of  five  digit  satellite  numbers 

vcClasses  -  vector  of  character  classification  'U'  for  unclassified 

vilntDesYears  -  vector  of  last  two  digits  of  launch  year 

viLaunchNumbers  -  vector  of  launch  number  of  the  year 

vstrPieces  -  vector  of  piece  of  the  launch 

viEpochYears  -  vector  of  last  two  digits  of  the  year 

vdEpochDaysOfYear  -  vector  of  day  and  fractional  day 

vdMeanMotionlstDerivs  -  vector  of  first  derivative  of  mean  motion 

vdMeanMotionZndDerivs  -  vector  of  second  derivative  of  mean  motion 

vdBStars  -  vector  of  b  star  drag  terms 

viEphemTypes  -  vector  of  ephemeris  types 

viElementNumbers  -  vector  of  element  numbers 

vstrTLELineZs  -  vector  of  strings  representing  line  2  of  the  two  line  element 
vdinclinations  -  vector  of  inclination  in  degrees 

vdRightAscensions  -  vector  of  right  ascension  of  ascending  node  in  degrees 
vdEccentricities  -  vector  of  eccentricities 
vdArgsofPerigee  -  vector  of  arguments  of  perigee  in  degrees 
vdMeanAnomalies  -  vector  of  mean  anomalies  in  degrees 
vdMeanMotions  -  vector  of  mean  motions,  in  revs  per  day 
vIEpochRevolutions  -  vector  of  revolution  numbers  at  epoch 

Return  values:  none 


void  setMeanElements 

(double  dElementTimeMJD, 
double  dlncllnation, 
double  dArgofPerigee, 
double  dMeanAnomaly, 
double  dMeanMotionlstDeriv, 
double  dEccentricity, 
double  dRightAscension, 
double  dMeanMotion, 
double  dMeanMotionZndDeriv, 
double  dBStar ) 

Usage:  Sets  the  required  mean  orbital  elements  when  using  orbital  elements 
to  drive  the  orbit  propagator. 

Parameters: 

dElementTimeMJD  -  date/time  (MJD)  of  the  orbital  elements 
dlncllnation  -  inclination  in  degrees 
dArgofPerigee  -  argument  of  perigee  in  degrees 
dMeanAnomaly  -  mean  anomaly  in  degrees 
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dMeanMotionlstDeriv  -  first  derivative  of  mean  motion 
dEccentricity  -  eccentricity 

dRightAscension  -  right  ascension  of  ascending  node  in  degrees 
dMeanMotion  -  mean  motion  in  revs  per  day 
dMeanMotionZndDeriv  -  second  derivitive  of  mean  motion 
dBStar  -  b  star  drag  term 

Return  values:  none 


void  setTimes 

( double  dStartMJD,  double  dEndMJD,  double  dTimestepSecs ) 

Usage:  Sets  the  time  range  and  cadence  for  calculating  ephemeris 
Parameters: 

dStartMJD  -  start  date/time  (in  MJD)  of  the  ephemeris  timeframe 
dEndMJD  -  end  date/time  (in  MJD)  of  the  ephemeris  timeframe 
dTimestepSecs  -  cadence  (in  seconds)  at  which  to  calculate  ephemeris 

Return  values:  none 


void  setTimes 

( const  vector<double>&  vdTimesMJD ) 

Usage:  Sets  times  at  which  to  generate  ephemeris  when  using  TLEs  to 
drive  the  orbit  propagator 

Parameters: 

vdTimesMJD  -  date/times  (in  MJD)  at  which  to  generate  ephemeris 
Return  values:  none 


void  setOrbitType 

(  const  Strings  strOrbit ) 

Usage:  Sets  the  type  of  orbit  to  compute  for  the  Kepler/J2  propagator.  Valid  values  are 
'classical',  'mean'/solar'/rv'/geosync'.  This  setting  dictates  which  orbital  elements  are 
required  for  input.  See  the  Ae9Ap9  User's  Guide  for  details. 

Parameters: 

StrOrbit  -  text  string  representing  above  Kepler  orbit  types 
Return  values:  none 
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void  setOrbitalElementEpoch 

(  double  dEpochMJD  ) 

Usage:  Sets  the  date  and  time  for  the  passed  orbital  element  (Kepler  only) 
Parameters: 

dEpochMJD  -  date  /time  (MJD)  of  orbital  element  epoch 
Return  values:  none 


void  setUseJZPerturbations 

(  bool  bUseJ2  ) 

Usage:  Enables  or  disables  computation  of  J2  perturbations  (Kepler  only) 
Parameters: 

bUseJ2  -  boolean  indicating  whether  to  use  J2  perturbation  computation 
Return  values:  none 


void  setinclination 

(  double  dInclinationInDeg ) 

Usage:  Sets  the  orbital  inclination  in  degrees  (Kepler  only) 
Parameters: 

dInclinationInDeg -orbital  inclination  in  degrees 
Return  values:  none 


void  setEccentricity 

(  double  dEccentricity ) 

Usage:  Sets  the  eccentricity  of  the  orbit  (Kepler  only) 
Parameters: 

dEccentricity  -  eccentricity  of  orbit 
Return  values:  none 
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void  setArgOfPerigee 

( double  dArgOfPerigeeInDeg ) 

Usage:  Sets  the  argument  of  perigee  in  degrees  (Kepler  only) 
Parameters: 

dArgOfPerigeeInDeg  -  argument  of  perigee  (Dg) 

Return  values:  none 


void  setMeanAnomalyAtEpoch 

( double  dMeanAnomalyInDeg  ) 

Usage:  Sets  the  mean  anomaly  at  the  epoch  time  (Dg)  (Kepler  only) 
Parameters: 

dMeanAnomalyInDeg  -  mean  anomaly  in  degrees 
Return  values:  none 


void  setMeanMotion 

(  double  dMeanMotionInRevPerDay ) 

Usage:  Sets  the  mean  motion  (rev/day)  (Kepler  only) 

Parameters: 

dMeanMotionInRevPerDay- mean  motion  in  rev/day 
Return  values:  none 


void  setRightAscension 

( double  dLongitudeInDeg ) 

Usage:  Sets  the  right  ascension  of  ascending  node  in  degrees  (Kepler  only) 
Parameters: 

dLongitudeInDeg  -longitude  of  ascending  node  (Dg) 

Return  values:  none 

void  setAltitudeOf Perigee 

(  double  dAltitudeInKm  ) 
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Usage:  Sets  the  altitude  (km)  at  perigee  (Kepler  only) 
Parameters: 

dAltitudeInKm  -  altitude  in  km  at  perigee 
Return  values:  none 


void  setAltitudeOf Apogee 

(  double  dAltitudeInKm  ) 

Usage:  Sets  the  altitude  (km)  at  apogee  (Kepler  only) 
Parameters: 

dAltitudeInKm  -  altitude  in  km  at  apogee 
Return  values:  none 


void  setLocalTimeOfApogee 

(  double  dLocalTimeInHours ) 

Usage:  Sets  the  local  time  (Mrs)  at  apogee  (Kepler  only) 
Parameters: 

dLocalTimeInHours  -  local  time  (hrs)  at  apogee 
Return  values:  none 


void  setLocalTimeOfMaxInclination 

(  double  dLocalTimeInHours ) 

Usage:  Sets  the  local  time  (hrs)  at  max  inclination  (Kepler  only) 
Parameters: 

dLocalTimeInHours  -  local  time  (hrs)  at  max  inclination 
Return  values:  none 

void  setTimeOf Perigee 

(  double  dTimeMJD  ) 

Usage:  Sets  the  time  (MJD)  of  perigee  (Kepler  only) 
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Parameters: 

dTimeMJD  -  time  in  MJD  of  perigee 
Return  values:  none 


void  setSemimajorAxis 

(  double  dAxisInRe  ) 

Usage:  Sets  the  length  (RE)  of  the  orbit  semimajor  axis  (Kepler  only) 
Parameters: 

dAxisInRe  -  length  in  RE  of  the  semimajor  axis 
Return  values:  none 


void  setPositionGE! 

(  double  dX,  double  dY,  double  dZ  ) 

Usage:  Sets  the  position  (GEI)  at  epoch  (orbital  element  time)  (Kepler  only) 
Parameters: 

dX,  dY,  dZ  -  vector  defining  position  in  GEI  at  epoch 
Return  values:  none 


void  setVelocityGEI 

(  double  dU,  double  dV,  double  dW  ) 

Usage:  Sets  the  velocity  (GEI)  at  epoch  (orbital  element  time)  (Kepler  only) 
Parameters: 

dU,  dV,  dW  -  vector  defining  velocity  in  GEI  at  epoch 
Return  values:  none 


void  setGeosyncLongitude 

(  double  dLongitudeDeg ) 

Usage:  Sets  the  longitude  (Dg)  for  a  geosynchronous  orbit  (Kepler  only) 
Parameters: 

dLongitudeDeg  -  longitude  (Dg)  of  a  geosynchronous  orbit 
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Return  values:  none 


void  setMagfieldModelDB 

(  const  Strings  strDb  ) 

Usage:  Sets  the  path  of  the  magnetic  field  model  database  for  use  in  coordinate 
conversions  by  the  Kepler  model. 

Parameters: 

StrDb  -  path  and  file  name  of  the  magnetic  field  model  db  (same  db  used  in  model). 
Return  values:  none 


int  computeEphemeris 

( vector<double>&  vdTimesMJD, 
vector<double>&  vdXsGEO, 
vector<double>&  vdYsGEO, 
vector<double>&  vdZsGEO, 
vector<double>&  vdXDotsGEO, 
vector<double>&  vdYDotsGEO, 
vector<double>&  vdZDotsGEO ) 

Usage:  Compute  ephemeris  for  previously  set  TIE  or  mean  elements  and  timeframe 
Parameters: 

vdTimesMJD  -  (returned)  vector  of  times  at  which  ephemeris  computed 
vdXsGEO  -  (returned)  vector  of  x  axis  components  of  positions 
vdYsGEO  -  (returned)  vector  of  y  axis  components  of  positions 
vdZsGEO  -  (returned)  vector  of  z  axis  components  of  positions 
vdXDotsGEO  -  (returned)  vector  of  x  axis  components  of  velocity 
vdYDotsGEO  -  (returned)  vector  of  y  axis  components  of  velocity 
vdZDotsGEO  -  (returned)  vector  of  z  axis  components  of  velocity 

Return  values: 

int  -  0  success,  else  (see  AEErrors.h) 


AEAggregator  Class 

base  class  (public  interface  for  all  aggregator  classes) 
Header  file:  AEAggregator.h 


Approved  for  public  release;  distribution  is  unlimited. 

20 


Description:  This  class  is  the  base  class  for  all  flux  aggregators  supplied  with  Ae9Ap9. 

Classes  derived  from  this  class  summarize  3d  floating  point  data  in  a  variety 
of  ways.  The  base  class  simply  defines  a  common  interface. 

Public  methods: 

AEAggregator 

Usage:  Default  constructor 

Parameters:  none 

Return  values:  none 

virtual  ""AEAggregator 

Usage:  Destructor 

Parameters:  none 

Return  values:  none 

virtual  void  reset 

Usage:  clears  in-progress  aggregated  results 
Parameters:  none 
Return  values:  none 


virtual  in  t  add 

( const  dvectorSi  vdDateTimes,  const  vvdvector&  vvvdData ) 

Usage:  inserts  new  data  into  an  existing  aggregation 
Parameters: 

vdDateTimes  -  vector  of  date/times  (in  MJD)  of  data  to  add  to  the  aggregation 
vvvdData  -  3d  vector  of  data  (time, energy, direction)  to  aggregate 
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Return  values: 

0  -  success,  else  error  (see  AEErrors.h) 


virtual  void  getAggregatedData 

{ dvectorSi  vdDateTimesMJD, 
vvd  vectors  vvvdData, 
bool  bincludeincompleteinterval  =  false  ) 

Usage:  retrieves  completed  aggregation  intervals,  and 
optionally,  the  one  currently  in  progress 

Parameters: 

vdDateTimesMJD  -  (return)  vector  of  date/times  (in  MJD)  of  aggregated  data 
vvvdData  -  (return)  3d  vector  of  aggregated  data  (time,energy,direction) 
bincludeincompleteinterval  -  if  true,  current  period  summed  even  if  short 
of  aggregation  interval  (usually  used  at  end  of  orbit) 

Return  values: 

0  -  success,  else  error  (see  AEErrors.h) 


virtual  void  clearAggregatedData 

Usage:  empties  the  collection  of  completed  aggregation  intervals 
Parameters:  none 
Return  values:  none 

int  getAggregationInterval 

Usage:  returns  the  aggregation  interval  (in  #  samples) 
Parameters:  none 
Return  values: 

int  -  aggregation  interval  (in  #  samples) 

void  setAggregationInterval 

( int  iNumSampies ) 
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Usage:  set  the  aggregation  interval  (in  #  samples) 

Parameters: 

iNumSamples  -  aggregation  interval  (in  number  of  samples) 
Return  values:  none 
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C  Language  API 


Header  file:  AECInterface.h 

Description:  AECInterface.h  provides  C  language  wrapper  functions  to  the  methods  of  the 

Ae9Ap9Application  class  described  above  in  the  C++  API  section  of  this  document. 
The  C  interface  can  be  used  to  access  the  model  when  linking  statically  or  as  a 
shared  object  or  dll.  Note  that  access  to  aggregation  classes  and  orbit  propagators 
are  not  currently  supported  through  the  C  interface. 

Methods: 


int  AE9AP9APP_setFluxEnvironment_c 

( char*  szModelType, 

char*  szFluxType, 

char*  szCoordSys, 

int  iNumEnergyLevels, 

int  iNumEnergyDims, 

doubie*  pdEnergies, 

int  iNumTimes, 

const  double*  pdTimes, 

const  double*  pdCoordsAxisl, 

const  double*  pdCoordsAxisl, 

const  double*  pdCoordsAxisS) 

Usage:  This  method  computes  flux  weights  for  a  grouping  of  satellite 
positions  at  a  given  set  of  energies  and  times  when  computing 
omnidirectional  flux.  It  should  be  called  once  prior  to  calling 
any  combination  of  fly-in  flux  computation  methods  for  that 
time  period.  Note:  use  as  large  a  grouping  of  satellite 
positions  as  can  be  processed  on  available  hardware. 

Parameters: 

szModelType  -  type  of  model  to  be  run:  Electron,  Proton,  ModelSpecies  (plasma) 
szFluxType  -  type  of  flux  to  compute  (1  point  differential  "IPTDIFF",  2  point 
differential  "2PTDIFF",  integral  "INTEGRAL") 
szCoordSys  -  coordinate  system  of  positions  and  directions:  GEO,  GEI,  GDZ, 

GSM,  GSE,  SSM,  MAG,  SPH,  RLL 

iNumEnergyLevels  -  number  of  energies  passed  (per  dimension) 
iNumEnergyDims  -  number  of  energy  dimensions  (1  unless  2pt.  diff  flux  type) 
pdEnergies  -  array  of  doubles  defining  energy  levels  (MeV)  at  which  to  compute 
flux.  Note:  column  2  used  only  for  2  pt  differential  flux  type,  which 
requires  computation  of  flux  between  two  energy  levels  (row  major) 
iNumTimes  -  number  of  time  values  passed  in  pdTimes 
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pdTimes  -  array  of  date/times  in  modified  Julian  date  format  at  which  to 
compute  flux.  Lengths  of  time  and  position  arrays  must  match, 
with  time  corresponding  to  a  position  at  the  same  index  in  the  arrays. 
pdCoordsAxisl, 
pdCoordsAxisZ, 

pdCoordsAxisS  -  Coordinates  along  axes  in  3d  space  in  the  eCoordSys  coordinate 
system  of  each  position  at  which  flux  is  to  be  computed.  These  arrays 
should  match  the  vdTimes  array  in  length  and  correspond  to  those 
times  at  each  position. 


Return  values: 

0  -  success,  else  error  (see  AEErrors.h) 


int  AE9AP9APP_setFluxEnvironmentDir_c 

( char*  szModelType, 
char*  szFluxType, 
char*  szCoordSys, 
int  iNumEnergyLevels, 
int  iNumEnergyDims, 
double*  pdEnergies, 
int  iNumTimes, 
const  double*  pdTImes, 
const  double*  pdCoordsAxIsl, 
const  double*  pdCoordsAxIsZ, 
const  double*  pdCoordsAxIsS, 
int  iNumDirs, 
double*  pdFluxDirl, 
double*  pdFluxDirZ, 
double*  pdFluxDir3 ) 


Usage:  returns  the  aggregation  interval  (in  #  samples) 

Parameters: 

szModelType  -  type  of  model  to  be  run:  Electron,  Proton,  ModelSpecies  (plasma) 
szFluxType  -  type  of  flux  to  compute  (1  point  differential  "IPTDIFF",  2  point 
differential  "2PTDIFF",  integral  "INTEGRAL") 
szCoordSys  -  coordinate  system  of  positions  and  directions:  GEO,  GEI,  GDZ, 

GSM,  GSE,  SSM,  MAG,  SPH,  RLL 

iNumEnergyLevels  -  number  of  energies  passed  (per  dimension) 
iNumEnergyDims  -  number  of  energy  dimensions  (1  unless  2pt.  diff  flux  type) 
pdEnergies  -  array  of  doubles  defining  energy  levels  (MeV)  at  which  to  compute 
flux.  Note:  column  2  used  only  for  2  pt  differential  flux  type,  which 
requires  computation  of  flux  between  two  energy  levels  (row  major) 
iNumTimes  -  number  of  time  values  passed  in  pdTimes 
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pdTimes  -  array  of  date/times  in  modified  Julian  date  format  at  which  to 
compute  flux.  Lengths  of  time  and  position  arrays  must  match, 
with  time  corresponding  to  a  position  at  the  same  index  in  the  arrays. 
pdCoordsAxisl, 
pdCoordsAxisZ, 

pdCoordsAxisS  -  Coordinates  along  axes  in  3d  space  in  the  eCoordSys  coordinate 
system  of  each  position  at  which  flux  is  to  be  computed.  These  arrays 
should  match  the  vdTimes  array  in  length  and  correspond  to  those 
times  at  each  position. 

iNumDirs  -  size  of  the  directions  dimension  in  the  2d  direction  arrays  below 

pdFluxDirl, 

pdFluxDirZ, 

pdFluxDir3  -  Directions  at  which  to  compute  flux  at  each  timestep.  Multiple 
directions  can  be  computed  at  each  timestep.  Thus,  the  arrays  are 
2d  (time,direction).  Defined  in  szCoordSys  coordinates 


Return  values: 

0  -  success,  else  error  (see  AEErrors.h) 


int  AE9AP9APP_flylnMean_c 

( double*  pdFluxData) 

Usage:  This  method  computes  mean  flux  at  each  position,  time,  energy  and 

optionally  direction  passed  in  the  most  recent  call  to  setFluxEnvironment. 
Bad  values  are  returned  as  AE_NaN  (defined  in  AEErrors.h). 

Parameters: 

pdFluxData  -(return)  3D  array  (time,energy,direction)  of  flux  data  (MeV) 
Sufficient  memory  should  be  allocated  by  caller,  as  follows: 

(#  times  passed  to  setFluxEnvironment  *  #  Energy  levels  * 

#  directions  [1  for  omni]),  storage  order:  row  major 
tleldl,  tleld2,  tleld3,  tle2dl,  tle2d2,  tle2d3,  t2eldl... 

Return  Values: 

int  -  0  success,  else  (see  AEErrors.h) 


int  AE9AP9APP_flylnPerturbedMean_c 

( int  iScenario,  double*  pdFluxData) 

Usage:  This  method  computes  perturbed  mean  flux  at  each  position,  time,  energy  and 
optionally  direction  passed  in  the  most  recent  call  to  setFluxEnvironment. 
Perturbed  means  are  a  statistical  distribution  of  mean  flux  based  on 
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measurement  uncertainty  only.  Bad  values  are  returned  as  AE_NaN  (defined 
in  AEErrors.h). 

Parameters: 

iScenario  -  perturbed  mean  scenario  number  (1..999)  for  repeatability 
pdFluxData  -(return)  3D  array  (time, energy, direction)  of  flux  data  (MeV) 
Sufficient  memory  should  be  allocated  by  caller,  as  follows: 

(#  times  passed  to  setFluxEnvironment  *  #  Energy  levels  * 

#  directions  [1  for  omni]),  storage  order:  row  major 
tleldl,  tleldZ,  tleldS,  tleZdl,  tle2d2,  tle2d3,  t2eldl... 

Return  values: 

int  -  0  success,  else  (see  AEErrors.h) 


int  AE9AP9APP_flylnPercentile_c 

( int  iPercentile,  double*  pdFluxData ) 

Usage:  This  method  computes  percentile  flux  at  each  position,  time,  energy  and 
optionally  direction  passed  in  the  most  recent  call  to  setFluxEnvironment. 

Bad  values  are  returned  as  AE_NaN  (defined  in  AEErrors.h).  The  function 
ae9ap9::isnan(value)  should  be  used  to  test  for  bad  values. 

Parameters: 

iPercentile  -  percentile  (1..99)  flux  to  compute  at  each  time,  energy  and  position 
pdFluxData  -(return)  3D  array  (time,energy,direction)  of  flux  data  (MeV) 
Sufficient  memory  should  be  allocated  by  caller,  as  follows: 

(#  times  passed  to  setFluxEnvironment  *  #  Energy  levels  * 

#  directions  [1  for  omni]),  storage  order:  row  major 
tleldl,  tleld2,  tleld3,  tle2dl,  tle2d2,  tle2d3,  t2eldl... 


Return  values: 

int  -  0  success,  else  (see  AEErrors.h) 


int  AE9AP9APP_flylnScenario_c 

( double  dEpoch, 
int  iScenario, 
double*  pdFluxData, 
bool  bPerturbFIuxMap  =  true ); 

Usage:  This  method  computes  monte  carlo  flux  at  each  position,  time,  energy  and 
optionally  direction  passed  in  the  most  recent  call  to  setFluxEnvironment. 
Monte  carlo  fluxes  are  a  statistical  distribution  of  flux  based  on  both 
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measurement  and  temporal  uncertainty.  Bad  values  are  returned  as 
AE_NaN  (defined  in  AEErrors.h). 

Parameters: 

dEpoch  -  start  date/time  (in  Modified  Julian  Date)  for  the  scenario 
iScenario  -  monte  carlo  scenario  number  (1..999)  for  repeatability 
pdFluxData  -(return)  3D  array  (time, energy, direction)  of  flux  data  (MeV) 
Sufficient  memory  should  be  allocated  by  caller,  as  follows: 
(#  times  passed  to  setFluxEnvironment  *  #  Energy  levels  * 

#  directions  [1  for  omni]),  storage  order:  row  major 
tleldl,  tleldZ,  tleldS,  tleZdl,  tleZdZ,  tle2d3,  tZeldl... 
bPerturbFIuxMap  -  if  false,  turns  off  measurement  uncertainty  mean 
perturbation.  Do  Not  Use.  For  testing  purposes  only. 

Return  values: 

int  -  0  success,  else  (see  AEErrors.h) 


const  char*  AE9AP9APP_getErrorText_c 

Usage:  retrieve  text  associated  with  a  returned  error  code 
Parameters:  none 
Return  values: 

const  char*  -  ptr  to  a  null  terminated  string  of  error  text 


int  AE9AP9APP_setModelDataSource_c 

{ const  char*  szDataSource,  int  iLength ); 

Usage:  Set  the  path  and  file  name  of  the  hdfS  format  database  containing 
the  data  of  the  selected  model,  (ie:  for  high  energy  electrons,  pass 
"{path}/  AE9V10_runtime_tables.mat")  Call  this  once  at  startup  to 
initialize  the  model. 

Parameters: 

szDataSource  -  path  and  file  name  of  the  hdfS  database 
iLength  -  length  of  the  path/file  name  string  passed 

Return  values: 

int  -  0  success,  else  (see  AEErrors.h) 
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int  AE9AP9APP_setKPhiNeuralNetDataSource_c 

( const  char*  szDataSource,  int  iLength ) 

Usage:  Set  the  path  and  file  name  of  the  hdfS  format  database  containing 
the  K/Phi  space  neural  network  used  by  the  selected  model. 

(ie:  pass  "{path}/  fastPhi_net.mat")  Call  this  once  at  startup  to  initialize 
the  model. 

Parameters: 

szDataSource  -  path  and  file  name  of  the  hdfS  neural  net  database 
iLength  -  length  of  the  path/file  name  string  passed 

Return  values: 

int  -  0  success,  else  (see  AEErrors.h) 


int  AE9AP9APP_setKHMinNeuralNetDataSource_c 

( const  char*  szDataSource, 
int  iLength  ); 

Usage:  Set  the  path  and  file  name  of  the  hdfS  format  database  containing 
the  K/Hmin  space  neural  network  used  by  the  selected  model. 

(ie:  pass  "{path}/  fast_hmin_net.mat")  Call  this  once  at  startup  to 
initialize  the  model. 


Parameters: 

szDataSource  -  path  and  file  name  of  the  hdfS  neural  net  database 
iLength  -  length  of  the  path/file  name  string  passed 


Return  values: 

int  -  0  success,  else  (see  AEErrors.h) 


int  AE9AP9APP_setMagfieldModelDataSource_c 

{ const  char*  szDataSource,  int  iLength ) 

Usage:  Set  the  path  and  file  name  of  the  hdfS  format  database  containing 
the  magnetic  field  model  data  used  by  the  selected  model. 

(ie:  pass  "{path}/  igrfDB.hS") .  Call  this  once  at  startup  to  initialize 
the  model. 

Parameters: 

szDataSource  -  path  and  file  name  of  the  hdfS  database 
iLength  -  length  of  the  path/file  name  string  passed 
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Return  values: 

int  -  0  success,  else  (see  AEErrors.h) 


void  AE9AP9APP_cleanup_c 

Usage:  Call  this  to  ensure  the  underlying  model  gets  deallocated. 

Failure  to  do  so  can  result  in  HDF5  console  messages  on  exit. 

Parameters:  none 

Return  values:  none 


const  char*  AE9AP9APP_getVersion_c 

Usage:  Call  to  obtain  version  number  of  Ae9Ap9  library  in  use 
Parameters:  none 
Return  values: 

const  char*  -  null  terminated  string  containing  Ae9Ap9  version 
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Fortran  API 


Header  file: 
Description: 

Methods: 

int  ae9ap9app 


AEFInterface.h 

AEFInterface.h  provides  Fortran  language  wrapper  functions  to  the  methods  of  the 
Ae9Ap9Application  class  described  above  in  the  C++  API  section  of  this  document. 
The  Fortran  interface  can  be  used  to  access  the  model  when  linking  statically  or  as  a 
shared  object  or  dll.  Note  that  access  to  aggregation  classes  and  orbit  propagators 
are  not  currently  supported  through  the  Fortran  interface. 


setfluxenvironment_f 

( char*  pchModelType, 
int*  piModelTypeLen, 
char*  pchFluxType, 
int*  piFluxTypeLen, 
char*  pchCoordSys, 
int*  piCoordSysLen, 
int*  piNumEnergies, 
int*  piNumEnergyDims, 
doubie*  pdEnergies, 
int*  piNumTimes, 
const  doubie*  pdTimes, 
const  doubie*  pdCoordsAxisl, 
const  doubie*  pdCoordsAxisl, 
const  doubie*  pdCoordsAxis3 ) 

Usage:  This  method  computes  flux  weights  for  a  grouping  of  satellite 
positions  at  a  given  set  of  energies  and  times  when  computing 
omnidirectional  flux.  It  should  be  called  once  prior  to  calling 
any  combination  of  fly-in  flux  computation  methods  for  that 
time  period.  Note:  use  as  large  a  grouping  of  satellite 
positions  as  can  be  processed  on  available  hardware. 

Parameters: 

pchModelType  -  type  of  model  to  be  run:  Electron,  Proton,  ModelSpecies  (plasma) 
piModelTypeLen  -  length  of  preceding  model  type  character  array 
pchFluxType  -  type  of  flux  to  compute  (1  point  differential  "IPTDIFF",  2  point 
differential  "2PTDIFF",  integral  "INTEGRAL") 
piFluxTypeLen  -  length  of  preceding  flux  type  character  array 
pchCoordSys  -  coordinate  system  of  positions  and  directions:  GEO,  GEI,  GDZ, 

GSM,  GSE,  SSM,  MAG,  SPH,  RLL 

piCoordSysLen  -  length  of  preceding  coordinate  system  character  array 
piNumEnergyLevels  -  number  of  energies  passed  (per  dimension) 
piNumEnergyDims  -  number  of  energy  dimensions  (1  unless  2pt.  diff  flux  type) 
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pdEnergies  -  array  of  doubles  defining  energy  levels  (MeV)  at  which  to  compute 
flux.  Note:  column  2  used  only  for  2  pt  differential  flux  type,  which 
requires  computation  of  flux  between  two  energy  levels  (row  major) 
piNumTimes  -  number  of  time  values  passed  in  pdTimes 
pdTimes  -  array  of  date/times  in  modified  Julian  date  format  at  which  to 
compute  flux.  Lengths  of  time  and  position  arrays  must  match, 
with  time  corresponding  to  a  position  at  the  same  index  in  the  arrays. 
pdCoordsAxisl, 
pdCoordsAxis2, 

pdCoordsAxisS  -  Coordinates  along  axes  in  3d  space  in  the  eCoordSys  coordinate 
system  of  each  position  at  which  flux  is  to  be  computed.  These  arrays 
should  match  the  vdTimes  array  in  length  and  correspond  to  those 
times  at  each  position. 


Return  values: 

0  -  success,  else  error  (see  AEErrors.h) 


int  ae9ap9app_setfluxenvironmentdir_f 

( char*  pchModelType, 
int*  piModelTypeLen, 
char*  pchFluxType, 
int*  piFluxTypeLen, 
char*  pchCoordSys, 
int*  piCoordSysLen, 
int*  piNumEnergies, 
int*  piNumEnergyDims, 
double*  pdEnergies, 
int*  piNumTimes, 
const  double*  pdTimes, 
const  double*  pdCoordsAxisl, 
const  double*  pdCoordsAxisl, 
const  double*  pdCoordsAxis3, 
int*  piNumFluxDirs, 
double*  pdFluxDirl, 
double*  pdFluxDirl, 
double*  pdFluxDir3 ); 

Usage:  This  method  computes  flux  weights  for  a  grouping  of  satellite 
positions  at  a  given  set  of  energies  and  times  when  computing 
directional  flux.  It  should  be  called  once  prior  to  calling 
any  combination  of  fly-in  flux  computation  methods  for  that 
time  period.  Note:  use  as  large  a  grouping  of  satellite 
positions  as  can  be  processed  on  available  hardware. 
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Parameters: 

pchModelType  -  type  of  model  to  be  run:  Electron,  Proton,  ModelSpecies  (plasma) 
piModelTypeLen  -  length  of  preceding  model  type  character  array 
pchFluxType  -  type  of  flux  to  compute  (1  point  differential  "IPTDIFF",  2  point 
differential  "2PTDIFF",  integral  "INTEGRAL") 
piFluxTypeLen  -  length  of  preceding  flux  type  character  array 
pchCoordSys  -  coordinate  system  of  positions  and  directions:  GEO,  GEI,  GDZ, 

GSM,  GSE,  SSM,  MAG,  SPH,  RLL 

piCoordSysLen  -  length  of  preceding  coordinate  system  character  array 
piNumEnergyLevels  -  number  of  energies  passed  (per  dimension) 
piNumEnergyDims  -  number  of  energy  dimensions  (1  unless  2pt.  diff  flux  type) 
pdEnergies  -  array  of  doubles  defining  energy  levels  (MeV)  at  which  to  compute 
flux.  Note:  column  2  used  only  for  2  pt  differential  flux  type,  which 
requires  computation  of  flux  between  two  energy  levels  (row  major) 
piNumTimes  -  number  of  time  values  passed  in  pdTimes 
pdTimes  -  array  of  date/times  in  modified  Julian  date  format  at  which  to 
compute  flux.  Lengths  of  time  and  position  arrays  must  match, 
with  time  corresponding  to  a  position  at  the  same  index  in  the  arrays. 
pdCoordsAxisl, 
pdCoordsAxis2, 

pdCoordsAxis3  -  Coordinates  along  axes  in  3d  space  in  the  eCoordSys  coordinate 
system  of  each  position  at  which  flux  is  to  be  computed.  These  arrays 
should  match  the  vdTimes  array  in  length  and  correspond  to  those 
times  at  each  position. 

piNumDirs  -  size  of  the  directions  dimension  in  the  2d  direction  arrays  below 

pdFluxDirl, 

pdFluxDir2, 

pdFluxDir3  -  Directions  at  which  to  compute  flux  at  each  timestep.  Multiple 
directions  can  be  computed  at  each  timestep.  Thus,  the  arrays  are 
2d  (time,direction).  Defined  in  szCoordSys  coordinates 


int  ae9ap9app_flyinmean_f 

( double*  pppdFluxData); 

Usage:  This  method  computes  mean  flux  at  each  position,  time,  energy  and 

optionally  direction  passed  in  the  most  recent  call  to  setFluxEnvironment. 
Bad  values  are  returned  as  AE_NaN  (defined  in  AEErrors.h). 

Parameters: 

pppdFluxData  -(return)  3D  array  (time,energy,direction)  of  flux  data  (MeV) 
Sufficient  memory  should  be  allocated  by  caller,  as  follows: 

(#  times  passed  to  setFluxEnvironment  *  #  Energy  levels  * 

#  directions  [1  for  omni]),  storage  order:  row  major 
tleldl,  tleld2,  tleld3,  tle2dl,  tle2d2,  tle2d3,  t2eldl... 
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Return  Values: 

int  -  0  success,  else  (see  AEErrors.h) 


int  ae9ap9app_flyinperturbedmean_f 

( int*  piScenario,  double*  pppdFluxData); 

Usage:  This  method  computes  perturbed  mean  flux  at  each  position,  time,  energy  and 
optionally  direction  passed  in  the  most  recent  call  to  setFluxEnvironment. 
Perturbed  means  are  a  statistical  distribution  of  mean  flux  based  on 
measurement  uncertainty  only.  Bad  values  are  returned  as  AE_NaN  (defined 
in  AEErrors.h). 

Parameters: 

piScenario  -  perturbed  mean  scenario  number  (1..999)  for  repeatability 
pppdFluxData  -(return)  3D  array  (time,energy,direction)  of  flux  data  (MeV) 
Sufficient  memory  should  be  allocated  by  caller,  as  follows: 

(#  times  passed  to  setFluxEnvironment  *  #  Energy  levels  * 

#  directions  [1  for  omni]),  storage  order:  row  major 
tleldl,  tleld2,  tleldS,  tle2dl,  tle2d2,  tle2d3,  t2eldl... 


Return  values: 

int  -  0  success,  else  (see  AEErrors.h) 


int  ae9ap9app_flyinpercentile_f 

( int*  piPercentile,  double*  pppdFluxData); 

Usage:  This  method  computes  percentile  flux  at  each  position,  time,  energy  and 
optionally  direction  passed  in  the  most  recent  call  to  setFluxEnvironment. 

Bad  values  are  returned  as  AE_NaN  (defined  in  AEErrors.h).  The  function 
ae9ap9::isnan(value)  should  be  used  to  test  for  bad  values. 

Parameters: 

piPercentile  -  percentile  (1..99)  flux  to  compute  at  each  time,  energy  and  position 
pppdFluxData  -(return)  3D  array  (time,energy,direction)  of  flux  data  (MeV) 
Sufficient  memory  should  be  allocated  by  caller,  as  follows: 

(#  times  passed  to  setFluxEnvironment  *  #  Energy  levels  * 

#  directions  [1  for  omni]),  storage  order:  row  major 
tleldl,  tleld2,  tleld3,  tle2dl,  tle2d2,  tle2d3,  t2eldl... 


Return  values: 

int  -  0  success,  else  (see  AEErrors.h) 
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int  ae9ap9app_flyinscenario_f 


( double*  pdEpoch, 
int*  piScenario, 
double*  pppdFluxData, 
bool*  pbPerturbFIuxMap  =  NULL  ); 

Usage:  This  method  computes  monte  carlo  flux  at  each  position,  time,  energy  and 
optionally  direction  passed  in  the  most  recent  call  to  setFluxEnvironment. 
Monte  carlo  fluxes  are  a  statistical  distribution  of  flux  based  on  both 
measurement  and  temporal  uncertainty.  Bad  values  are  returned  as 
AE_NaN  (defined  in  AEErrors.h). 

Parameters: 

pdEpoch  -  start  date/time  (in  Modified  Julian  Date)  for  the  scenario 
piScenario  -  monte  carlo  scenario  number  (1..999)  for  repeatability 
pppdFluxData  -(return)  3D  array  (time,energy,direction)  of  flux  data  (MeV) 
Sufficient  memory  should  be  allocated  by  caller,  as  follows: 

(#  times  passed  to  setFluxEnvironment  *  #  Energy  levels  * 

#  directions  [1  for  omni]),  storage  order:  row  major 
tleldl,  tleldZ,  tleldS,  tleZdl,  tleZdZ,  tle2d3,  tZeldl... 
pbPerturbFIuxMap  -  if  false,  turns  off  measurement  uncertainty  mean 
perturbation.  Do  Not  Use.  For  testing  purposes  only. 

Return  values: 

int  -  0  success,  else  (see  AEErrors.h) 


Int  ae9ap9app_geterrortext_f 

( char*  pchErrorText,  int*  piLength); 

Usage:  retrieve  text  associated  with  a  returned  error  code 


Parameters: 

pchErrorText  -  buffer  to  hold  error  text 
piLength  -  max  length  of  text  (buffer  size) 


Return  values: 

int  -  0  success,  else  (see  AEErrors.h) 


int  ae9ap9app_setmodeldatasource_f 

( const  char*  pchDataSource,  int*  piLength ); 

Usage:  Set  the  path  and  file  name  of  the  hdfS  format  database  containing 
the  data  of  the  selected  model,  (ie:  for  high  energy  electrons,  pass 
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"{path}/  AE9V10_runtime_tables.mat")  Call  this  once  at  startup  to 
initialize  the  model. 

Parameters: 

pchDataSource  -  path  and  file  name  of  the  hdf5  database 
piLength  -  length  of  the  path/file  name  string  passed 

Return  values: 

int  -  0  success,  else  (see  AEErrors.h) 


int  ae9ap9app_setkphineuralnetdatasource_J 

( const  char*  pchDataSource, 
int*  piLength  ); 

Usage:  Set  the  path  and  file  name  of  the  hdfS  format  database  containing 
the  K/Phi  space  neural  network  used  by  the  selected  model. 

(ie:  pass  "{path}/  fastPhi_net.mat")  Call  this  once  at  startup  to  initialize 
the  model. 

Parameters: 

pchDataSource  -  path  and  file  name  of  the  hdfS  neural  net  database 
piLength  -  length  of  the  path/file  name  string  passed 

Return  values: 

int  -  0  success,  else  (see  AEErrors.h) 


int  ae9ap9app_setkhminneuralnetclatasource_f 

( const  char*  pchDataSource, 
int*  piLength  ); 

Usage:  Set  the  path  and  file  name  of  the  hdfS  format  database  containing 
the  K/Hmin  space  neural  network  used  by  the  selected  model. 

(ie:  pass  "{path}/  fast_hmin_net.mat")  Call  this  once  at  startup  to 
initialize  the  model. 

Parameters: 

pchDataSource  -  path  and  file  name  of  the  hdfS  neural  net  database 
piLength  -  length  of  the  path/file  name  string  passed 

Return  values: 

int  -  0  success,  else  (see  AEErrors.h) 
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int  ae9ap9app_setmagfieldmodeldatasource_f 

( const  char*  pchDataSource, 
int*  piLength  ); 

Usage:  Set  the  path  and  file  name  of  the  hdfS  format  database  containing 
the  magnetic  field  model  data  used  by  the  selected  model. 

(ie:  pass  "{path}/  igrfDB.hS") .  Call  this  once  at  startup  to  initialize 
the  model. 


Parameters: 

pchDataSource  -  path  and  file  name  of  the  hdfS  database 
piLength  -  length  of  the  path/file  name  string  passed 


Return  values: 

int  -  0  success,  else  (see  AEErrors.h) 


void  ae9ap9app_cleanup_J 

Usage:  Call  this  to  ensure  the  underlying  model  gets  deallocated. 

Failure  to  do  so  can  result  in  HDFS  console  messages  on  exit. 

Parameters:  none 

Return  values:  none 


int  ae9ap9app_getversion_f 

( char*  pchVersionText,  int*  piLength); 


Usage:  Call  to  obtain  version  number  of  Ae9Ap9  library  in  use 
Parameters: 

pchVersionText  -  buffer  to  hold  version  number  text 
piLength  -  size  of  buffer 

Return  values: 

int  -  0  success,  else  (see  AEErrors.h) 
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